Analysis-task conventions: task_paths, task template, AGENTS.md - #12
Closed
Marius1311 wants to merge 3 commits into
Closed
Analysis-task conventions: task_paths, task template, AGENTS.md#12Marius1311 wants to merge 3 commits into
Marius1311 wants to merge 3 commits into
Conversation
Adds the working conventions for agent-run analysis tasks, so a repo made from this template starts consistent instead of growing its own layout. A task is one session, one worktree, one branch, one directory. Its outputs split by durability rather than by kind: tracked `results/`/`reports/` stay in the calling checkout and ride the PR, while untracked `figures/`/`outputs/`/`logs/` are anchored to the main checkout so they survive the worktree being removed. `task_paths(__file__)` resolves both. The anchoring is why `main_checkout()` uses `git rev-parse --git-common-dir` rather than `FilePaths.ROOT`: `_find_root` walks up for a `.git` marker, and a worktree's `.git` is a file that exists, so it stops at the worktree. Untracked output would then be written somewhere that later disappears — silently, since worktrees are gitignored and git never warns about them. Also: - `.gitignore` gains `outputs/` and `logs/` (unanchored, matching at any depth) plus negations so a task's small evidence tables and HTML report stay tracked — they are what a reviewer actually reads on GitHub. - `AGENTS.md` carries the conventions; `CLAUDE.md` is a pointer to it, and `copilot-instructions.md` defers to it rather than restating. The top-level `figures/` keeps its role for curated output (talks, papers), which is distinct from task output. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VYsKhgGuNCFtxqFhSLGtCK
…r-agnostic The template shipped an Euler-flavoured slurm/ pair that restated four facts owned by the euler-slurm skill (--output semantics, the missing-log-dir requeue loop, sbatch idiom, MAIN resolution) — two of them already drifted: OMP_NUM_THREADS was dropped while requesting 8 CPUs, and the requeue loop was described as a silent failure. The one fact the template owns is a path fact, not a scheduler fact: log paths come from task_paths().logs and are passed absolutely. That is now stated once, without naming a scheduler. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VYsKhgGuNCFtxqFhSLGtCK
… instructions Paths had two parallel mechanisms. `_find_root` walked up for a marker while `main_checkout` asked git, and `FilePaths.ROOT` used the former — so central data would resolve into a worktree if the package were ever installed from one, the hazard AGENTS.md had to warn about. There is now one resolver, git-first with the marker walk as fallback, and `FilePaths.ROOT` is it. `DatasetPaths` and `TaskPaths` were the same idea twice with different spellings (properties vs fields, `create()` vs `ensure()`). Both are now field-only dataclasses over a shared base with a single `create()`, and both are built by expanding the directory-name tuples, so a directory name is written once. `EXAMPLE_DATASET` is gone: `FilePaths.dataset()` is the one way to reach a dataset. The copilot instructions restated AGENTS.md; they are now a pointer, matching CLAUDE.md, and the session rule no longer names a specific agent's exit command. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VYsKhgGuNCFtxqFhSLGtCK
Member
Author
|
Superseded by #13, which keeps only the housekeeping half: agent-neutral guidance (AGENTS.md canonical, CLAUDE.md and copilot instructions as pointers) and a single git-based root resolver with dataset paths as a directory set. The analysis-task conventions — Branch |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds working conventions for agent-run analysis tasks, so a repo made from this template starts consistent instead of growing its own layout. Ported from what we settled in
gli3_merscope_analysisand generalised.The model
A task is one agent session, one worktree, one branch, one directory (
analysis/<topic>/.../<name_vN>/). Its outputs split by durability, not by kind:results/,reports/figures/,outputs/,logs/task_paths(__file__)resolves both.Why
main_checkout()doesn't useFilePaths.ROOT_find_rootwalks up for a.gitmarker. A worktree's.gitis a file, and it exists, so it stops at the worktree. Untracked output would then be written into a directory that later disappears — silently, because worktrees are gitignored so git never warns about them.git rev-parse --path-format=absolute --git-common-dirgives the main checkout from any worktree.The same trap catches Slurm:
--outputresolves against the submit directory, soslurm/submit.shpasses it absolutely.Data rules
AGENTS.mdstates the ones that are genuinely general: accumulate by addition (commutative, so concurrent sessions can't lose each other's work); never write your in-memory object back over a shared one; which object is current is stated per session and recorded in the task README rather than hardcoded, which is how a config ends up pointing at something retired months ago.Other changes
.gitignoregainsoutputs/andlogs/(unanchored, matching at any depth), plus negations so a task's small evidence tables and HTML report stay tracked — they are what a reviewer actually reads on GitHub.AGENTS.mdowns the conventions;CLAUDE.mdis a pointer to it andcopilot-instructions.mddefers to it rather than restating, so there is one owner per fact.figures/keeps its role for curated output (talks, papers), which is distinct from task output.Notebook conventions are unchanged — humans work in the main checkout and the same output rules apply.
🤖 Generated with Claude Code
https://claude.ai/code/session_01VYsKhgGuNCFtxqFhSLGtCK